Clarify note on customized built-ins support in Safari

[justinfagnani]

Description

Re-order the custom element types to put the most supported type first and make the note about customized built-ins more useful.

I replaced the note here with the note from the is= attribute page, which is a lot more clear and informative.

Motivation

The "Using Custom Elements" page lists customized build-ins first in the discussion of types of custom elements, even though it isn't and won't be supported in Safari. It seems like we should mention the cross-browser supported feature first.

Also, the note on this page doesn't actually say anything about the implementation status, but links to the is= attribute, making it harder to see that Safari will not implement the feature.

Additional details

Related issues and pull requests

[github-actions]

[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

	> [!NOTE]
	> Please see the [`is`](/en-US/docs/Web/HTML/Global_attributes/is) attribute reference for caveats on implementation reality of custom built-in elements.
	- **Autonomous custom elements** inherit from the HTML element base class {{domxref("HTMLElement")}}. You have to implement their behavior from scratch.
	> [Safari does not plan to support custom built-in elements](https://github.com/WebKit/standards-positions/issues/97) and [browser vendors are exploring alternative solutions to customizing built-ins](https://github.com/WICG/webcomponents/issues/1029). Check the [browser compatibility](#browser_compatibility) section for support information.
	> [!NOTE] > [Safari does not plan to support custom built-in elements](https://github.com/WebKit/standards-positions/issues/97) and [browser vendors are exploring alternative solutions to customizing built-ins](https://github.com/WICG/webcomponents/issues/1029). Check the [browser compatibility](#browser_compatibility) section for support information.

[github-actions]

Preview URLs

• /en-US/docs/Web/API/Web_components/Using_custom_elements

External URLs (2)

URL: /en-US/docs/Web/API/Web_components/Using_custom_elements
Title: Using custom elements

• Proposal: Custom attributes for all elements, enhancements for more complex use cases WICG/webcomponents#1029 (1 time) (Note! This may be a new URL 👀)
• Customized built-in elements WebKit/standards-positions#97 (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-08-16 17:46:00)

[Josh-Cena]

+0.5 for reordering, -1 for replacing the note. The point here is to have a single source of truth to explain about the Safari situation, so if we have more explanations to add or the situation changes, we don't need to find all mentions. This note is at the very top of is so I don't think it's undiscoverable.

[justinfagnani]

@Josh-Cena

-1 for replacing the note. The point here is to have a single source of truth to explain about the Safari situation, so if we have more explanations to add or the situation changes, we don't need to find all mentions. This note is at the very top of is so I don't think it's undiscoverable.

The problem is that the key takeaway - that Safari will not implement this feature - is buried on a page that's about one aspect of the feature. It's not just the is= attribute that doesn't work, Safari also ignores the extends option, and throws if you try to construct a custom element that extends a built-in other than HTMLElement.

This doesn't work in Safari and doesn't use the is= attribute:

customElements.define('my-button', class extends HTMLButtonElement {}, {extends: 'button'});
document.createElement('my-button');

So if there should be a single source of truth, the is= attribute page is the wrong place.

But also, this piece of information is so important that is could be clearly mentioned as a caveat on every feature related to customized built-ins. I think it's not clear enough to new readers to say "click here for caveats" rather than "this feature will never work on Safari" right where they're reading.

[Josh-Cena]

We are pretty set on the principle that "don't duplicate information if it's possible; link to one canonical source of explanation". define() not having this note was an oversight of mine but otherwise it would be linking to the is page too. I don't have preferences for where to put it, though—if you don't like its current location I'm totally fine to make https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements (the current place you are modifying) or even the https://developer.mozilla.org/en-US/docs/Web/API/Web_components landing page the source of truth. The upshot is I anticipate a lot of nuance that people may want to add/explain/change, especially since the spec discussion is still ongoing, so we should prepare for those situations and be friendly for casual contributors who aren't aware that they need to modify so many places to keep MDN consistent. (For example, whatever conclusion we reach here, if we modify the note, we would need to do the same change to https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#web_component_example and https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#customized_built-in_elements)

[justinfagnani]

@Josh-Cena ok, so how about if I move the canonical location of the note to "Using Custom Elements" and add the redirect note to is and define()?

[Josh-Cena]

Yep, that sounds good (and the other locations I pointed above, which already have this note)

[Josh-Cena]

@justinfagnani Do you plan to come back to work on this?

[Josh-Cena]

@justinfagnani I played with this and I think it's best to link to is. This is because the is page is the only page with a browser compatibility table that explicitly says "unsupported in Safari". It will take a few jumps for readers to find the whole picture, but it's the best in terms of single-source-of-truth (especially if implementation status ever changes). Therefore I would like to keep the docs as-is. Thanks for the PR!